<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Basic Installation</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="index.html" title="Smarty 3 Manual">
<link rel="up" href="installation.html" title="Chapter 2. Installation">
<link rel="prev" href="installation.html" title="Chapter 2. Installation">
<link rel="next" href="installing.smarty.extended.html" title="Extended Setup">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center">Basic Installation</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="installation.html">Prev</a> </td>
<th width="60%" align="center">Chapter 2. Installation</th>
<td width="20%" align="right"> <a accesskey="n" href="installing.smarty.extended.html">Next</a>
</td>
</tr>
</table>
<hr>
</div>
<div class="sect1" title="Basic Installation">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="installing.smarty.basic"></a>Basic Installation</h2></div></div></div>
<p>
    Install the Smarty library files which are in the
    <code class="filename">/libs/</code>  sub directory of
    the distribution. These are <code class="filename">.php</code> files that you
    SHOULD NOT edit. They are shared among all applications and only get
    changed when you upgrade to a new version of Smarty.
   </p>
<p>In the examples below the Smarty tarball has been  unpacked to:
   </p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem"><p>
   <code class="filename">/usr/local/lib/Smarty-v.e.r/</code> for *nix
   machines</p></li>
<li class="listitem"><p> and
   <code class="filename">c:\webroot\libs\Smarty-v.e.r\</code> for the
   windows environment.</p></li>
</ul></div>
<p>
   </p>
<div class="example">
<a name="id341680"></a><p class="title"><b>Example 2.1. Required Smarty library files</b></p>
<div class="example-contents"><pre class="screen">

Smarty-v.e.r/
   libs/
      Smarty.class.php
      debug.tpl
      sysplugins/* (everything)
      plugins/*    (everything)

    </pre></div>
</div>
<br class="example-break"><p>
    Smarty uses a PHP <a class="ulink" href="http://php.net/define" target="_top">constant</a>
    named <a class="link" href="smarty.constants.html#constant.smarty.dir" title="SMARTY_DIR"><code class="constant">SMARTY_DIR</code>
    </a> which is the <span class="bold"><strong>full system file path</strong></span>
    to the Smarty <code class="filename">libs/</code> directory.
    Basically, if your application can find  the
    <code class="filename">Smarty.class.php</code> file, you do not need to set the
    <a class="link" href="smarty.constants.html#constant.smarty.dir" title="SMARTY_DIR"><code class="constant">SMARTY_DIR</code></a>
    as Smarty will figure it out on its own.
    Therefore, if
    <code class="filename">Smarty.class.php</code> is not in your
    <a class="ulink" href="http://php.net/ini.core.php#ini.include-path" target="_top">include_path</a>,
    or you do not supply an absolute path to it in your application,
    then you must define <code class="constant">SMARTY_DIR</code> manually.
    <code class="constant">SMARTY_DIR</code> <span class="bold"><strong>must include a
    trailing slash/</strong></span>.
   </p>
<div class="informalexample">
<p>
    Here's how you create an instance of Smarty in your PHP scripts:
   </p>
<pre class="programlisting">

&lt;?php
// NOTE: Smarty has a capital 'S'
require_once('Smarty.class.php');
$smarty = new Smarty();
?&gt;

    </pre>
</div>
<p>
    Try running the above script. If you get an error saying the
    <code class="filename">Smarty.class.php</code> file could not be found, you need to
    do one of the following:
   </p>
<div class="example">
<a name="id341782"></a><p class="title"><b>Example 2.2. Set SMARTY_DIR constant manually</b></p>
<div class="example-contents"><pre class="programlisting">

&lt;?php
// *nix style (note capital 'S')
define('SMARTY_DIR', '/usr/local/lib/Smarty-v.e.r/libs/');

// windows style
define('SMARTY_DIR', 'c:/webroot/libs/Smarty-v.e.r/libs/');

// hack version example that works on both *nix and windows
// Smarty is assumend to be in 'includes/' dir under current script
define('SMARTY_DIR',str_replace("\\","/",getcwd()).'/includes/Smarty-v.e.r/libs/');

require_once(SMARTY_DIR . 'Smarty.class.php');
$smarty = new Smarty();
?&gt;

    </pre></div>
</div>
<br class="example-break"><div class="example">
<a name="id341795"></a><p class="title"><b>Example 2.3. Supply absolute path to library file</b></p>
<div class="example-contents"><pre class="programlisting">

&lt;?php
// *nix style (note capital 'S')
require_once('/usr/local/lib/Smarty-v.e.r/libs/Smarty.class.php');

// windows style
require_once('c:/webroot/libs/Smarty-v.e.r/libs/Smarty.class.php');

$smarty = new Smarty();
?&gt;

    </pre></div>
</div>
<br class="example-break"><div class="example">
<a name="id341817"></a><p class="title"><b>Example 2.4. Add the library path to the <code class="filename">php.ini</code> file</b></p>
<div class="example-contents"><pre class="programlisting">

;;;;;;;;;;;;;;;;;;;;;;;;;
; Paths and Directories ;
;;;;;;;;;;;;;;;;;;;;;;;;;

; *nix: "/path1:/path2"
include_path = ".:/usr/share/php:/usr/local/lib/Smarty-v.e.r/libs/"

; Windows: "\path1;\path2"
include_path = ".;c:\php\includes;c:\webroot\libs\Smarty-v.e.r\libs\"

</pre></div>
</div>
<br class="example-break"><div class="example">
<a name="id341846"></a><p class="title"><b>Example 2.5. Appending the include path in a php script with
    <code class="literal"><a class="ulink" href="http://php.net/ini-set" target="_top">ini_set()</a></code></b></p>
<div class="example-contents"><pre class="programlisting">

&lt;?php
// *nix
ini_set('include_path', ini_get('include_path').PATH_SEPARATOR.'/usr/local/lib/Smarty-v.e.r/libs/');

// windows
ini_set('include_path', ini_get('include_path').PATH_SEPARATOR.'c:/webroot/lib/Smarty-v.e.r/libs/');
?&gt;

    </pre></div>
</div>
<br class="example-break"><p>
    Now that the library files are in place, it's time to setup the Smarty
    directories for your application:</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem"><p>
    Smarty requires four directories which
    are by default named <code class="filename">templates/</code>,
    <code class="filename">templates_c/</code>, <code class="filename">configs/</code> and <code class="filename">cache/</code>
    </p></li>
<li class="listitem"><p>Each of these are definable by the
    Smarty class properties
    <a class="link" href="variable.template.dir.html" title="$template_dir">
    <code class="varname">$template_dir</code></a>,
    <a class="link" href="variable.compile.dir.html" title="$compile_dir">
    <code class="varname">$compile_dir</code></a>,
    <a class="link" href="variable.config.dir.html" title="$config_dir">
    <code class="varname">$config_dir</code></a>, and
    <a class="link" href="variable.cache.dir.html" title="$cache_dir">
    <code class="varname">$cache_dir</code></a> respectively
    </p></li>
<li class="listitem"><p>
      It is highly recommended
      that you setup a separate set of these directories for each application
      that will use Smarty
     </p></li>
<li class="listitem"><p>
      You can verify if your system has the correct access rights for these directories with 
      <a class="link" href="api.test.install.html" title="testInstall()"><code class="varname">testInstall()</code></a>.
     </p></li>
</ul></div>
<p>
    For our installation example, we will be setting up the Smarty environment
    for a guest book application. We picked an application only for the purpose
    of a directory naming convention. You can use the same environment for any
    application, just replace <code class="literal">guestbook/</code> with
    the name of your application.
    </p>
<div class="example">
<a name="id341973"></a><p class="title"><b>Example 2.6. What the file structure looks like</b></p>
<div class="example-contents"><pre class="screen">

/usr/local/lib/Smarty-v.e.r/libs/
        Smarty.class.php
        debug.tpl
        sysplugins/*
        plugins/*

/web/www.example.com/
        guestbook/
        templates/
            index.tpl
        templates_c/
        configs/
        cache/
        htdocs/
            index.php

    </pre></div>
</div>
<br class="example-break"><p>
    Be sure that you know the location of your web server's document root as a
    file path. In the following examples, the document root is <code class="filename">/web/www.example.com/guestbook/htdocs/</code>.
    The Smarty
    directories are only accessed by the Smarty library and never accessed
    directly by the web browser. Therefore to avoid any security concerns, it
    is recommended (but not mandatory) to place these directories
    <span class="emphasis"><em>outside</em></span> of the web server's document root.
   </p>
<p>
    You will need as least one file under your document root, and that is the
    script accessed by the web browser. We will name our script
    <code class="filename">index.php</code>, and place it in a subdirectory under the
    document root <code class="filename">/htdocs/</code>.
   </p>
<p>
    Smarty will need <span class="bold"><strong>write access</strong></span>
    (windows users please ignore) to the
    <a class="link" href="variable.compile.dir.html" title="$compile_dir">
    <em class="parameter"><code>$compile_dir</code></em></a> and
    <a class="link" href="variable.cache.dir.html" title="$cache_dir">
    <em class="parameter"><code>$cache_dir</code></em></a> directories
    (<code class="filename">templates_c/</code> and
    <code class="filename">cache/</code>), so be sure the web server
    user account can write  to them.

    </p>
<div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>This is usually user <span class="quote">“<span class="quote">nobody</span>”</span> and
    group <span class="quote">“<span class="quote">nobody</span>”</span>. For OS X users,
    the default is user <span class="quote">“<span class="quote">www</span>”</span> and group <span class="quote">“<span class="quote">www</span>”</span>.
    If you are using Apache, you can  look in your
    <code class="filename">httpd.conf</code> file to see
    what user and group are being used.</p>
</div>
<p>
    </p>
<div class="example">
<a name="id342090"></a><p class="title"><b>Example 2.7. Permissions and making directories writable</b></p>
<div class="example-contents"><pre class="programlisting">

chown nobody:nobody /web/www.example.com/guestbook/templates_c/
chmod 770 /web/www.example.com/guestbook/templates_c/

chown nobody:nobody /web/www.example.com/guestbook/cache/
chmod 770 /web/www.example.com/guestbook/cache/

    </pre></div>
</div>
<br class="example-break"><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>
     <code class="literal">chmod 770</code> will be fairly tight security, it only allows
     user <span class="quote">“<span class="quote">nobody</span>”</span> and group <span class="quote">“<span class="quote">nobody</span>”</span> read/write access
     to the directories. If you would like to  open up read access to anyone
     (mostly for your own convenience of viewing
     these files), you can use <code class="literal">775</code> instead.
    </p>
</div>
<p>
    We need to create the <code class="filename">index.tpl</code> file that Smarty will
    display. This needs to be located in the <a class="link" href="variable.template.dir.html" title="$template_dir">
    <em class="parameter"><code>$template_dir</code></em></a>.
   </p>
<div class="example">
<a name="id342155"></a><p class="title"><b>Example 2.8. /web/www.example.com/guestbook/templates/index.tpl</b></p>
<div class="example-contents"><pre class="screen">

{* Smarty *}

Hello {$name}, welcome to Smarty!

    </pre></div>
</div>
<br class="example-break"><div class="note" title="Technical Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Technical Note</h3>
<p>
     <code class="literal">{* Smarty *}</code> is a template
     <a class="link" href="language.basic.syntax.html#language.syntax.comments" title="Comments">comment</a>.
     It is not required, but it is good
     practice to start all your template files with this comment. It makes
     the file easy to recognize regardless of the file extension. For
     example, text editors could recognize the file and turn on special
     syntax highlighting.
    </p>
</div>
<p>
    Now lets edit <code class="filename">index.php</code>. We'll create an instance of Smarty,
    <a class="link" href="api.assign.html" title="assign()"><code class="varname">assign()</code></a> a
    template variable and <a class="link" href="api.display.html" title="display()"><code class="varname">display()</code></a>
    the <code class="filename">index.tpl</code> file.
   </p>
<div class="example">
<a name="id342216"></a><p class="title"><b>Example 2.9. Editing /web/www.example.com/docs/guestbook/index.php</b></p>
<div class="example-contents"><pre class="programlisting">

&lt;?php

require_once(SMARTY_DIR . 'Smarty.class.php');

$smarty = new Smarty();

$smarty-&gt;setTemplateDir('/web/www.example.com/guestbook/templates/');
$smarty-&gt;setCompileDir('/web/www.example.com/guestbook/templates_c/');
$smarty-&gt;setConfigDir('/web/www.example.com/guestbook/configs/');
$smarty-&gt;setCacheDir('/web/www.example.com/guestbook/cache/');

$smarty-&gt;assign('name','Ned');

//** un-comment the following line to show the debug console
//$smarty-&gt;debugging = true;

$smarty-&gt;display('index.tpl');

?&gt;

    </pre></div>
</div>
<br class="example-break"><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>
     In our example, we are setting absolute paths to all of the Smarty
     directories. If <code class="filename">/web/www.example.com/guestbook/</code> is
     within your PHP include_path, then these settings are not necessary.
     However, it is more efficient and (from experience) less error-prone to
     set them to absolute paths. This ensures that Smarty is getting files
     from the directories you intended.
    </p>
</div>
<p>
    Now navigate to the <code class="filename">index.php</code> file with the web browser.
    You should see <span class="emphasis"><em>"Hello Ned, welcome to Smarty!"</em></span>
   </p>
<p>
    You have completed the basic setup for Smarty!
   </p>
</div>
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="installation.html">Prev</a> </td>
<td width="20%" align="center"><a accesskey="u" href="installation.html">Up</a></td>
<td width="40%" align="right"> <a accesskey="n" href="installing.smarty.extended.html">Next</a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Chapter 2. Installation </td>
<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
<td width="40%" align="right" valign="top"> Extended Setup</td>
</tr>
</table>
</div>
</body>
</html>
